home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1993 / MacHack 1993.toast / MacHack™ 1987-1992 / MacHack™ '90 / Source Code ƒ / TLC&TLP1.01aƒ / readme.tlc next >
Encoding:
Text File  |  1990-06-14  |  8.1 KB  |  189 lines  |  [TEXT/MPS ]
  1.     Copyright 1987-1989, Eduard Schwan Programs [esp]
  2.                 All rights reserved
  3. TLC (The Last C-Cross-Referencer) and TLP (same, but for
  4. Pascal) are Source Code Cross-Reference Generators crafted
  5. and shot into the Public Domain by Eduard Schwan.  The
  6. source code, documentation and executable program may be
  7. freely distributed as long as the copyright/author notices
  8. remain intact, and it is not used in part or whole as the
  9. basis of a commercial product without the author's
  10. permission. Any comments, bug-fixes, ports or enhancements
  11. are most welcome. Also, if you find TLC and it's source
  12. code useful, a contribution of $20 (check/money order) is
  13. encouraged!  Hopefully we will all see more source code
  14. distributed!  
  15.     Eduard Schwan, 1112 Oceanic Drive, Encinitas, Calif. 92024
  16.     (619) 632-0466 5:00PM - 8:00PM PST
  17. --------------------------------------------------------------------------
  18.  
  19. A quick note about the source code:
  20.  
  21. There are really two programs intertwined in this source.
  22. TLC is a C source cross-referencer, and TLP (a recent
  23. addition) is a Pascal source cross- referencer.  I wanted
  24. to put a real parser in here to help identify variable
  25. usage (declaration, reference, assignment), but of course,
  26. it was needed before it was done, and some quickie smarts
  27. were inserted instead, just to get it working.  Of course,
  28. I have not yet gone back to replace the parser, and
  29. probably never will.. it is good enough for me, and I'm
  30. lazy! Anyway, TLC came first, and all the files named
  31. TLCxxxx.C are needed to compile TLC.  TLP came later as an
  32. appendage to TLC.  It uses many of these TLCxxx files too,
  33. and it additionally needs all the TLPxxxx.C files. The MPW
  34. Make files are included here (TLC.MAKE and TLP.MAKE), but a
  35. table below should show you who uses what.
  36.  
  37. DOCUMENT        NEEDED BY            NEEDED BY            NEEDED BY
  38. FILE            BOTH                TLC                    TLP
  39. ---------        ----------            -----------            -----------
  40. readme.tlc        tlc.ext                tlc.c                tlp.c
  41. tlcHelp.Doc        tlc.h                tlc.make            tlp.make
  42.                 tlccmd.c            tlcgtok.c            tlpgtok.c
  43.                 tlcparm.c            tlcparm.dat            tlpparm.dat
  44.                 tlcparm.h            tlcprocf.c            tlpprocf.c
  45.                 tlcresw.c            tlcresw.dat            tlpresw.dat
  46.                 tlcsetp.c
  47.                 tlcstat.c
  48.                 tlcutil.c
  49.                 tlcxref.c
  50.  
  51.  
  52. Source code history:
  53.  
  54. TLC was originally written on a 64k Apple II+ in Aztec C65,
  55. then ported to APW C on an Apple IIGS, then to MPW C on an
  56. Apple Macintosh II.  I have not done any regression testing
  57. after adding the compiler switches, but it should still run
  58. on a IIGS (It does compile..:).  I am sure it has grown far
  59. too big for even the Aztec Interpreted C on the Apple II. I
  60. have not yet ported it to an MS-DOS machine, but it should
  61. go about as smoothly as the other ports. 
  62.  
  63. I have not made an effort to group machine-specific
  64. functions, but they hopefully just turned out that way..
  65. all in TLCUTIL.C.  Namely get_time(), get_mem(),
  66. check_user_abort(), and maybe do_form_feed().  Also check
  67. out TLC.H thoroughly. Some interesting constants are hiding
  68. in there.  You shouldn't need to diddle any of them, unless
  69. you are porting it to another machine. 
  70.  
  71. This has been a three year (not-so-copious) spare-time
  72. effort on my part, and I am hoping that this will be as
  73. useful to you as it has been to me.  If you are interested
  74. in porting this to yet another machine, or have comments or
  75. bug reports, or just want to say "hi" or send me money,
  76. please do feel free to contact me.  I am on AppleLink
  77. (JL.TECH, atten:Eduard Schwan), or at the address below.
  78. If you need serious quick assistance, I can be reached at
  79. home at the phone number listed, at the time listed.
  80. Have fun with it!  TTFN,
  81.  
  82.     Eduard Schwan
  83.     1112 Oceanic Drive
  84.     Encinitas, California  92024
  85.     (619) 632-0466 between 5:00pm and 8:00pm PST only, please.
  86.  
  87. --------------------------------------------------------------------------
  88.  
  89. These are the known bugs/features-to-be-added to
  90. The Last [C/Pascal] Cross-referencer, as of 7/02/89 (v1.01) [esp]:
  91.  
  92.     1:Xref case-sensitivity isn't here yet (do_case_sens/do_xcase_sens).
  93.       That is, one can't have case-sens. ids without having case-sens.
  94.       xref sorting, or vice versa.  DoCaseSens works, but DoXcaseSens
  95.       is ignored.  The way I did the symbol table, it is an icky chore
  96.       and may never show up, but hey, I haven't needed it yet either.
  97.  
  98.     2:Underscore-significance (Pascal) isn't here yet.
  99.       (now it is.. 0.90 beta)
  100.  
  101.     3:Include file handling isn't here yet.  Not only that, but the scanner
  102.       doesn't recognize the <incfile.h> as a string, so "incfile" and "h"
  103.       show up as separate xref'ed identifiers (hmm, could be called a feature?)
  104.     
  105.     4:The full-blown parser isn't here yet, instead some quickie C smarts
  106.       were kludged into the scanner (tlc.gtok.c) to make this useable in
  107.       a "reasonable" time frame.
  108.       (NOTE: as of 1.01, it now looks like a pain to retrofit it in..)
  109.       
  110.     5:The symbol table is 100% memory-resident, and therefore the size of
  111.       the source code you throw at TLC is limited by available heap space.
  112.       Another parameter (DO_BIG_XREF?) should be added that makes tlc/tlp
  113.       call alternate symbol table routines that do disk I/O..
  114.       
  115.     6:The statistics option should print out more interesting stuff someday..
  116.       (v1.00 added a list of file names..)
  117.     
  118.     7:The Macintosh version should be jazzed up with heap-avail displayed
  119.       every once in awhile, and it needs a commando interface for us lazies,
  120.       and the time/date need to be called & stuck into ctime_string in
  121.       tlc.util.c.
  122.       (heapAvail & time/date was just fixed in 0.95 beta, so ??? no longer
  123.       appears for time/date.)
  124.  
  125.     8:An fopen() in MPW C (Macintosh) creates a typeless, creatorless file
  126.       (to be expected, really) which means the output text file (TLC.OUT)
  127.       cannot immediately be read by any text editors.  I could either:
  128.         1. make TLC  write to stdout & redirect
  129.         2. tell users to type "setfile -t TEXT -c 'MPS ' tlc.out" after
  130.             running TLC in MPW, or
  131.         3. find a way to set the TYPE of the file inside TLC.
  132.       C purists would argue that redirecting to stdout is the way it should be
  133.       done, to which I say, "yeah, I should have made it that way in the
  134.       beginning.."  It doesn't look that hard to change, but I am still
  135.       pondering the ramifications..
  136.  
  137.     9:TLC knows what a function declaration is by blindly deciding that any
  138.       identifier followed by an open paren (that is not a #define macro) at
  139.       block level zero is a function decl.  This works 100% of the time when
  140.       the C source code's { } match up.  But the following (avoidable) practice
  141.       will goof up TLC's ability to detect functions beyond this point:
  142.               a = b;
  143.             if (a == 1)
  144.     #ifdef debug_on /* TLC ignores conditional compilation & does it all */
  145.                 {    /* in one.. */
  146.                 b = 3;
  147.     #else
  148.                 {  /* in two.. */
  149.                 b = 4;
  150.     #endif
  151.                 }    /* out two.. but not to one! */
  152.  
  153.       This can be avoided by fully capturing (or not capturing) braces in
  154.       conditionals:
  155.               a = b;
  156.             if (a == 1)
  157.     #ifdef debug_on
  158.                 {    /* in one.. */
  159.                 b = 3;
  160.                 }    /* out one */
  161.     #else
  162.                 {  /* in one again.. */
  163.                 b = 4;
  164.                 }    /* out one */
  165.     #endif
  166.  
  167.     10:Emphasis only works on the xref symbols.  It doesn't yet work for
  168.        function headers, comments, or reserved words in the listing output.
  169.  
  170.     11:I think TLC sometimes forgets a reference or two in BIG xref.s with
  171.        lots of files.  I think I have only seen it happen, but only a couple
  172.        of times, and am tracking it down now.
  173.        (Fairly exhaustive debugging with lotsa xreffed files turned up nothing..
  174.        I am giving up this search until a known repeatable occurrance is found,
  175.        so v1.00 may still have this problem!?)
  176.        (Aha! Found!  TLC was skipping the last line of every file.
  177.        If it happened to be an end-comment, then TLC would continue to
  178.        think it was in a comment as it went into the next source file..
  179.        until it found the first end comment there!)
  180.  
  181.     12:If only a cross-reference is done, a bunch of spaces are put in the
  182.        beginning of the file.  I think TLC.PROCF.C is the culprit, and not
  183.        all output is suppressed..
  184.        (Nope, it was new_page, fixed it with an additional parm. in v1.00)
  185.  
  186.     13:The source file names were changed in v1.00 to names edible by the
  187.        MS-DOS community, just in case portability happens.. All names with
  188.        multiple periods got the 1st period stripped (TLC.PROCF.C => TLCPROCF.C)
  189.